home *** CD-ROM | disk | FTP | other *** search
/ IRIX 6.2 Development Libraries / SGI IRIX 6.2 Development Libraries.iso / dist / complib.idb / usr / share / catman / p_man / cat3 / complib / psldlt.z / psldlt
Text File  |  1996-03-14  |  8KB  |  265 lines
  1.  
  2.  
  3.  
  4. PPPPSSSSLLLLDDDDLLLLTTTT((((3333FFFF))))                                                          PPPPSSSSLLLLDDDDLLLLTTTT((((3333FFFF))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      PSLDLT_Preprocess, PSLDLT_Factor, PSLDLT_Solve, PSLDLT_Destroy,
  10.      PSLDLT_Ordering - parallel sparse symmetric linear system solver
  11.  
  12. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  13.      PSLDLT solves sparse symmetric linear systems of the form
  14.         Ax = b
  15.      where A is an n x n symmetric input matrix, b is an input vector of
  16.      length n, and x is an unknown vector of length n.  PSLDLT uses a direct
  17.      method: A is factored into the form
  18.        A = L D L-transpose
  19.      where L is a lower triangular matrix with unit diagonal and D is a
  20.      diagonal matrix.
  21.  
  22.      The PSLDLT library contains four main routines.  PSLDLT_Preprocess()
  23.      performs preprocessing operations on the structure of A (heuristic
  24.      reordering to reduce fill in L, symbolic factorization, etc.).
  25.      PSLDLT_Factor() factors the matrix A into L and D, using the previously
  26.      computed preprocessing data.  PSLDLT_Solve() solves for a vector x, given
  27.      an input vector b.  PSLDLT_Destroy() frees all storage associated with
  28.      the matrix A (including L, D, and various data structures computed during
  29.      preprocessing).  Note that the user can call PSLDLT_Factor() several
  30.      times after a single call to PSLDLT_Preprocess() to factor multiple
  31.      matrices with identical non-zero structures but different values.
  32.      Similarly, the user can call PSLDLT_Solve() several times after a single
  33.      call to PSLDLT_Factor() to solve for multiple right-hand-sides.
  34.  
  35.      Sparse matrix A must be input to PSLDLT in Harwell-Boeing format (also
  36.      known as Compressed Column Storage format).  The matrix is held in three
  37.      arrays: pointers[], indices[], and values[].  The indices[] array
  38.      contains the row indices of the non-zeros in A.  The values[] array holds
  39.      the corresponding non-zero values.  The pointers[] array contains the
  40.      index in indices[] for the first non-zero in each column of A.  Thus, the
  41.      row indices for the non-zeros in column i can be found in locations
  42.      indices[pointers[i]] through indices[pointers[i+1]-1].  The corresponding
  43.      values can be found in location values[pointers[i]] through
  44.      values[pointers[i+1]-1].
  45.  
  46.      For a symmetric matrix A, the user must input either the lower or upper
  47.      triangle of A, but not both.  Non-zeroes within a column of A can be
  48.      stored in any order.
  49.  
  50.      To give an example, the following symmetric matrix...
  51.              1.0   symmetric
  52.              0.0 3.0
  53.              2.0 0.0 5.0
  54.              0.0 4.0 0.0 6.0
  55.  
  56.      would be represented in FORTRAN as follows:
  57.  
  58.              pointers[] = {1, 3, 5, 6, 7}
  59.              indices[] = {1, 3, 2, 4, 3, 4}
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. PPPPSSSSLLLLDDDDLLLLTTTT((((3333FFFF))))                                                          PPPPSSSSLLLLDDDDLLLLTTTT((((3333FFFF))))
  71.  
  72.  
  73.  
  74.              values[] = {1.0, 2.0, 3.0, 4.0, 5.0, 6.0}
  75.  
  76.      Zero-based indexing is used in C, so the pointers[] and indices[] arrays
  77.      would instead contain:
  78.  
  79.              pointers[] = {0, 2, 4, 5, 6}
  80.              indices[] = {0, 2, 1, 3, 2, 3}
  81.  
  82.      The routine PSLDLT_Ordering allows the user to change the ordering method
  83.      used to pre-order the matrix before factorization.  This routine must be
  84.      called before calling PSLDLT_Preprocess.  Three options are currently
  85.      available: method 0 performs no pre-ordering, method 1 (the default)
  86.      performs Approximate Minimum Degree ordering, and method 2 performs
  87.      multi-level nested dissection ordering.  Method 2 is significantly more
  88.      expensive than method 1, but it often produces significantly better
  89.      orderings.
  90.  
  91.      The environment variable MPC_NUM_THREADS determines the number of
  92.      processors that are used for the numerical factorization.  Setting the
  93.      environment variable PSLDLT_VERBOSE causes PSLDLT to output information
  94.      about the factorization.
  95.  
  96.  
  97. FFFFOOOORRRRTTTTRRRRAAAANNNN SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  98.      SUBROUTINE PSLDLT_PREPROCESS (TOKEN, N, POINTERS, INDICES, NONZ, OPS)
  99.  
  100.          INTEGER TOKEN, N
  101.  
  102.          INTEGER POINTERS( * ), INDICES( *)
  103.  
  104.          INTEGER NONZ,
  105.  
  106.          DOUBLE PRECISION OPS
  107.  
  108.  
  109.      SUBROUTINE PSLDLT_FACTOR (TOKEN, N, POINTERS, INDICES, VALUES)
  110.  
  111.          INTEGER TOKEN, N
  112.  
  113.          INTEGER POINTERS( * ), INDICES( * )
  114.  
  115.          DOUBLE PRECISION VALUES( * )
  116.  
  117.  
  118.      SUBROUTINE PSLDLT_SOLVE (TOKEN, X, B)
  119.  
  120.          INTEGER TOKEN
  121.  
  122.          DOUBLE PRECISION X( * ), B( * )
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. PPPPSSSSLLLLDDDDLLLLTTTT((((3333FFFF))))                                                          PPPPSSSSLLLLDDDDLLLLTTTT((((3333FFFF))))
  137.  
  138.  
  139.  
  140.      SUBROUTINE PSLDLT_DESTROY (TOKEN)
  141.  
  142.          INTEGER TOKEN
  143.  
  144.      SUBROUTINE PSLDLT_DESTROY (TOKEN, METHOD)
  145.  
  146.          INTEGER TOKEN
  147.  
  148.          INTEGER METHOD
  149.  
  150. CCCC SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  151.      void PSLDLT_Preprocess (
  152.  
  153.          int token,
  154.  
  155.          int n,
  156.  
  157.          int pointers[],
  158.  
  159.          int indices[],
  160.  
  161.          int *nonz,
  162.  
  163.          double *ops
  164.  
  165.          );
  166.  
  167.      void PSLDLT_Factor (
  168.  
  169.          int token,
  170.  
  171.          int n,
  172.  
  173.          int pointers[],
  174.  
  175.          int indices[],
  176.  
  177.          double values[]
  178.  
  179.          );
  180.  
  181.      void PSLDLT_Solve (
  182.  
  183.          int token,
  184.  
  185.          double x[],
  186.  
  187.          double b[]
  188.  
  189.          );
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. PPPPSSSSLLLLDDDDLLLLTTTT((((3333FFFF))))                                                          PPPPSSSSLLLLDDDDLLLLTTTT((((3333FFFF))))
  203.  
  204.  
  205.  
  206.      void PSLDLT_Destroy (
  207.  
  208.          int token
  209.  
  210.          );
  211.  
  212.      void PSLDLT_Ordering (
  213.  
  214.          int token,
  215.  
  216.          int method
  217.  
  218.          );
  219.  
  220.  
  221. AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS
  222.      token (input)
  223.              PSLDLT can handle multiple matrices simultaneously.  The token
  224.              distinguishes between active matrices.  The token passed to
  225.              PSLDLT_Factor() must match the token used in some previous call
  226.              to PSLDLT_Preprocess().  Similarly, the token passed to
  227.              PSLDLT_Solve() must match the token used in some previous call to
  228.              PSLDLT_Factor().
  229.  
  230.      n (input)
  231.              The number of rows and columns in the matrix A.  n >= 0.
  232.  
  233.      pointers, indices, values (input)
  234.              The pointers and indices arrays store the non-zero structure of
  235.              sparse input matrix A in Harwell-Boeing or Compressed Sparse
  236.              Column (CSC) format.  The pointers array stores n+1 integers,
  237.              where pointers[i] gives the index in indices of the first non-
  238.              zero in column i of A.  The indices array stores the row indices
  239.              of the non-zeros in A.  The nz array stores the non-zero values
  240.              in the matrix A.
  241.  
  242.      nonz, ops (output)
  243.              The number of non-zero values in L, and the number of floating-
  244.              point operations required to factor A.
  245.  
  246.      b (input)
  247.              The right-hand-side vector in a PSLDLT_Solve call.
  248.  
  249.      x (output)
  250.              The solution vector in a PSLDLT_Solve call.
  251.  
  252. TTTTUUUUNNNNIIIINNNNGGGG
  253.      Optimized and parallelized for the SGI R8000 platform.
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.